 dMMMMMMP .aMMMb  dMMMMb  .aMMMb dMMMMMMP dMMMMb  dMMMMMP dMMMMMP 
   dMP   dMP"dMP dMP VMP dMP"dMP   dMP   dMP.dMP dMP     dMP      
  dMP   dMP dMP dMP dMP dMP dMP   dMP   dMMMMK" dMMMP   dMMMP     
 dMP   dMP.aMP dMP.aMP dMP.aMP   dMP   dMP"AMF dMP     dMP        
dMP    VMMMP" dMMMMP"  VMMMP"   dMP   dMP dMP dMMMMMP dMMMMMP

fast todo scanner for your codebase

I always wanted a simple way to know how many tasks I have left in the repo, and which sections of the project have more remaining work.

grep finds TODOs. but grep doesn't respect .gitignore, doesn't give you a clean tree view organized by file. doesn't tell you "src/parser has 8 TODOs, but tests/parser has only 2". doesn't have a timeout.

so i built todotree.

      
        
        
      
src/main.rs

  L12   add CLI args
  L41   benchmark parser

src/parser/lexer.rs

  L89   optimize tokenizer

────────────────────────────
7 TODOs • 2 files • 9ms

single binary. no dependencies. scans your codebase in parallel, respects .gitignore, and shows you exactly where things are unfinished.

My daily setup

this is my favorite invocation:

      
        bash
        
      
todotree -pattern "TODO|FIXME" -time -git-root=true -timeout 1s -format tree -theme nord

searches for both TODOs and FIXMEs, shows execution time, auto-finds the git root, stops after 1 second so it never hangs, tree format with the nord color theme.

i integrated it into my shell so it runs every time i cd into any project:

      
        bash
        
      
function replace_cd(){
  if builtin cd "$@"; then
    if [ -d "$PWD/.git" ]; then
        echo "\n" && onefetch . && echo "\n" && todotree -pattern "TODO|FIXME" -time -git-root=true -timeout 1s -format tree -theme nord
    fi
  fi
}

alias cd="replace_cd"

TODOTREE

features

respects .gitignore, skips binaries
parallel scanning with timeout
auto git root detection
3 output formats: tree, list, json
6 color themes
depth limit, extension filter, regex patterns

quick start

      
        bash
        
      
go install github.com/danial2026/todotree@latest

cd your-project
todotree

search for TODO and FIXME, case insensitive:

      
        bash
        
      
todotree -pattern "TODO|FIXME" -i

output as JSON with execution time:

      
        bash
        
      
todotree -format json -time

with a color theme:

      
        bash
        
      
todotree -theme dracula -format list

limit depth, filter extensions:

      
        bash
        
      
todotree -depth 2 -ext ".go,.rs"

How it works

loads .gitignore patterns from the root directory
walks the directory tree in parallel using a worker pool
skips files matching gitignore, binary detection, and exclude list
scans remaining files with the regex pattern
outputs sorted results in the chosen format
respects timeout context -- clean cancellation on timeout

Flags

flag	default	description
`-dir`	`.`	root directory
`-depth`	`-1`	max depth (-1 for unlimited)
`-git-root`	`true`	auto-find git repository root
`-pattern`	`TODO`	search pattern (regex)
`-i`	`false`	case insensitive
`-ext`		file extensions to include (comma separated)
`-exclude`	`.git,node_modules,vendor,dist,build,target`	directories to exclude
`-workers`	CPU count	number of parallel workers
`-timeout`	`2s`	max execution time
`-time`	`false`	show execution time
`-format`	`tree`	output format (tree, list, json)
`-theme`	`default`	color theme (default, dracula, monokai, nord, onedark, solarized)

Supported Themes

theme	colors
default	none (plain text)
dracula	purple/cyan/orange
monokai	white/orange/red
nord	steel/teal/purple
onedark	blue/orange/peach
solarized	teal/orange/brown

Performance

tested on the linux kernel tree (~74k files):

the default 2s timeout catches it before it runs away
with -timeout 10s, it processes roughly 15k+ files
most projects complete in under 50ms

the timeout is the key feature for daily shell integration. you never want a missed cd to hang your terminal.

Notes

-git-root accepts multiple formats: -git-root true, -git-root=false, -git-root 1, -git-root yes
all string flags support space-separated and equals syntax: -dir /path or -dir=/path

Links

github.com/danial2026/todotree